Apple WWDC 1996/WWDC96_1996 (CD).toast/Technology Materials/MacOS 8 Resources/Developer Tools/Mac OS 8 Interfaces & Libraries/Interfaces/IDLIncludes/TextEngineSystem.idl

Text File | 1996-05-01 | 17KB | 456 lines

/*
     File:        TextEngineSystem.idl

     Contains:    IDL interface for the TextEngineSystem class

     Version:    Technology:    8.0
                 Release:    Universal Interfaces 3.0d3 on Copland DR1

     Copyright:    © 1995-1996 by Apple Computer, Inc.  All rights reserved.

     Bugs?:        If you find a problem with this file, send the file and version
                 information (from above) and the problem description to:

                     Internet:    [e-mail]
                     AppleLink:    APPLE.BUGS
*/


#ifndef __TEXTENGINESYSTEM_IDL__
#define __TEXTENGINESYSTEM_IDL__

#ifndef __CONDITIONALMACROS_IDL__
#include <ConditionalMacros.idl>
#endif

#include <somobj.idl>
#include <somcls.idl>

#include <Types.idl>
#include <Quickdraw.idl>
#include <Collections.idl>
#include <Drag.idl>
#include <Events.idl>
#include <AppleEvents.idl>
#include <TextObjects.idl>
#include <TextCommon.idl>
#include <TextEdit.idl>
#include <TextEngineTypes.idl>

interface TSystemTextEngine : SOMObject
{
// ======================================================
// Initialization
// ======================================================

    OSStatus InitTextInstance (in CGrafPtr port,in Rect bounds,
                                in OptionBits textEngineOptions);


// ======================================================
// View and image rectangles
// ======================================================

    // rectangle where text will be formatted
    // a null value in right or ottom means variable width/height
    //variable height should always be supported
    OSStatus SetTextFrameDimensions(in UInt32 width,  in UInt32 height) ;

    OSStatus GetTextFrameDimensions(out UInt32 width,  out UInt32 height) ;

    // rectangle where text will be imaged
    OSStatus SetTextViewFrame(in Rect viewFrameRect) ;

    OSStatus GetTextViewFrame(out Rect viewFrameRect) ;

    // rectangle contating offsets to to add to left top and remove from bottom right
    //of the text frame
    OSStatus SetTextMargins(in Rect marginOffsets) ;

    OSStatus GetTextMargins(out Rect marginOffsets) ;
    //update the text in the given rectangle in QuickDraw coordinates (view)
    //in the given CGrafPtr (assuming no refromatting is needed
    //if formatting is needed you should call AboutToImage before
    OSStatus RefreshText(in CGrafPtr whichPort,in Rect qDRectToUpdate) ;

    OSStatus EnableDrawingText();
    OSStatus DisableDrawingText();
    boolean  IsDrawingTextEnabled();

    //call this if your text is not wysiwyg, so it'll be reflowed according
    //to the pageDimensions (pageDimensions should be the text Frame after computing
    //the margins
    //AboutToImage will save the state of the current text instance and
    //reformat the text according to the new dimensions
    //Be aware that updating the window between AboutToImage  and EndImaging
    //(calling RefreshText with the window grafport) will result in wrong display.
    OSStatus     AboutToImage( in Rect pageDimensions );

    //restore the text state to what it was before calling AboutToImage
    OSStatus    EndImaging();
//======================================================
//    UI commmand
//======================================================

    OSStatus EnableUICommand();

    OSStatus DisableUICommand();

    boolean IsUICommandEnabled();

//======================================================
    OSStatus DoIDleAction();
// ======================================================
// Scrap and storage operations
// ======================================================
    //Set the whole text from a standard format (text+scrap style table)
    //this is the format every engine know to export / import
    // but it doesn't contain any new attributes (lang,region,encoding)
    OSStatus SetWholeTextTo(in Ptr textPtr , in ByteCount textSizeInBytes,
                            in StScrpPtr styleScrapPtr) ;

    // get the size of the text
    OSStatus GetWholeTextSize(out ByteCount textSizeInBytes);

    // copy all the text in textPtr , should retur memFullerr if storageSize< real text size
    OSStatus WriteWholeTextToPtr(in Ptr textPtr , in ByteCount storageSize);

    // return the number of runs for a style scrap table to the whole text
    OSStatus GetWholeScrapStyleCount(out ItemCount nRuns);

    // write the scrap style , should retur memFullerr if nRuns< real count of runs
    OSStatus  WriteWholeScrapStyleToPtr(in StScrpPtr styleScrapPtr , in ItemCount nRuns);

    // get the size of a native format to be exported or saved
    OSStatus GetStorageSizeForTextDataStructure(out ByteCount textInstanceStorageSizeInBytes);

    OSStatus SaveDataStructureToPtr(in Ptr theStorage, in ByteCount storageSizeAvailable);

    OSStatus ReadDataStructureFromPtr(in Ptr theStorage, in ByteCount storageSize);

// ======================================================
// Text insertion/deletion/replacement
// ======================================================

    // replace the specified range (inclusive) by the given TextObject
    // if the range to be deleted has unique language/region/encoding and the TextObject is mono-Run
    //    with the same     language/region/encoding as the deleted range than the inserted text  will inherit
    // the same attribute else new style run(s) will be created with the suitable attributes
    OSStatus SetText(in ByteOffset startIndex, in ByteOffset endIndex, in TextObject theText );

    //special version of SetText to replace the selected text
    //(critical routine used for inserting from the user input)
    OSStatus InsertText(in TextObject theText);

    OSStatus DeleteText(in ByteOffset startIndex, in ByteOffset endIndex)        ;
    // detete the given range of text

    //should we have another that return a Ptr ???
    OSStatus GetText( in ByteOffset startIndex, in ByteOffset endIndex ,out TextObject newTextObject );

// ======================================================
// selection / Scrolling / height
// ======================================================

    OSStatus SelectTextRange(in ByteOffset startIndex, in ByteOffset endIndex) ;

    OSStatus GetSelectedTextRange( out ByteOffset startIndex, out ByteOffset endIndex );


    OSStatus RevealTextRange( in ByteOffset startIndex, in ByteOffset endIndex, in boolean revealBegin );

    OSStatus ScrollTextViewTo(in UInt32 dh, in UInt32 dv) ;

    OSStatus GetScroll(out UInt32 dh, out UInt32 dv) ;

    //height of all lines included in  the given range
    OSStatus GetTextHeight(in ByteOffset startIndex, in ByteOffset endIndex,out UInt32 height) ;

// ======================================================
// Text attributes
// ======================================================
    // given one attribute set it value
    //this is a low level API for getting & setting one attribute
    OSStatus SetTextAttribute( in ByteOffset startIndex, in ByteOffset endIndex,
                         in TextAttributeTag theAttribute,
                         in void* theValuePtr, in ByteCount theValueSize);

    // Caller should allocate the data size (we assume that he knows the type of the value
    //he is asking for.
    OSStatus GetTextAttribute( in ByteOffset startIndex, in ByteOffset endIndex,
                         in TextAttributeTag theAttribute,
                         in ByteCount theAvailableSize,
                         out void* theValuePtr,
                         out ByteCount theValueSize );



// ======================================================
// attribute iteration routines
// ======================================================
    OSStatus NewTextAttributeIterator( in ByteOffset startIndex, in ByteOffset endIndex,
                                        in Collection textAttributeFilterCollection,
                                        out TextAttributeIteratorRef iterationRef );
    //    Create a Text Attribute iterator for the specified text range.
    //    The application specifies the attributes of interest in a collection whose...
    //        1.    'tags' are the attribute identifiers
    //        2.    'collectionUser0Bit'of attribute if set specifies "wild card" value.
    //        3.    'data' portion is value to match during iteration (if not wild card iteration).
    //    The resulting iterator will allow the application to iterate over the text range, and identify
    //    portions of the text which match (in value) the attributes specified in the original collection,
    //    and/or iterate over different attribute runs for those attributes for which "wild card" is specified.
    // The default iterator (nil collection) will iterate on every attribute change (always forward)

    OSStatus TextAttributeIterateForward( in TextAttributeIteratorRef iterationRef,
                                            out ByteOffset startIndex, out ByteOffset endIndex,
                                            in Collection textAttrCollection );

    //should we add an iterate backward

    OSStatus DisposeTextAttributeIterator(in TextAttributeIteratorRef iterationRef) ;

    OSStatus SetTextCollectionAttribute( in ByteOffset startIndex, in ByteOffset endIndex,
                         in Collection textAttrCollection);
    //    For every attribute in the filter collection specified, set the attributes of the text Range to
    //    the values specified in the collection.

    OSStatus GetSharedTextAttribute( in ByteOffset startIndex, in ByteOffset endIndex,
                                     in Collection textAttrCollection );
    //    Return all the attributes which are continuous over the specified text range.  Attributes which
    //    are not continuous over the text range are not included in the collection returned.

// ======================================================
// text  iteration routines
// ======================================================
    OSStatus GetNextTextElement(in ByteOffset fromIndex,in TextIterationtype elmentType , out ByteOffset startIndex , out ByteOffset endIndex) ;

    OSStatus GetPriorTextElement(in ByteOffset fromIndex,in TextIterationtype elmentType, out ByteOffset startIndex , out ByteOffset endIndex) ;

    OSStatus GetEnclosingTextElement(in ByteOffset fromIndex,
            in TextIterationtype elmentType,
            out ByteOffset startIndex ,
            out ByteOffset endIndex);
// ======================================================
// helpful offset to xxx routines
// ======================================================
    //Point is in the local port coordinate
    //and refer to the position of the character at ByteOffset (leading edge=true)
    OSStatus ByteOffsetToPixel (in ByteOffset offset, out Point pixel);

    OSStatus PixelToByteOffset (in Point pixel ,out ByteOffset offset);
//////////
    //word enclosing the given offset (error if not a word)
    OSStatus ByteOffsetToWord (in ByteOffset offset, out ByteOffset startIndex , out ByteOffset endIndex);


    //1 based
    OSStatus NthWordInRange(in ByteOffset startRangeOffset ,in ByteOffset endRangeOffset,in ItemCount wordIndex, out ByteOffset startIndex , out ByteOffset endIndex);

//////////
    //LineNo are relative to all the text
    //lines are dependant on layout informations
    OSStatus LineToByteOffsets (in ItemCount lineNo , out ByteOffset startIndex , out ByteOffset endIndex);

    //lines are dependant on layout informations
    OSStatus ByteOffsetToLine (in ByteOffset offset, out ItemCount lineNo);
//////////

    OSStatus ByteOffsetToParagraph (in ByteOffset offset, out ByteOffset paragraphStartIndex , out ByteOffset paragraphEndIndex);
// ======================================================
// helpful count elements routines
// ======================================================
    OSStatus GetCountChars(in ByteOffset offset, out ByteOffset startIndex, out UInt32 charCount);

    OSStatus GetCountWords(in ByteOffset offset, out ByteOffset startIndex, out UInt32 wordCount);

    //lines are dependant on layout informations
    OSStatus GetCountLines(in ByteOffset offset, out ByteOffset startIndex, out UInt32 lineCount);

    OSStatus GetCountParagraphs(in ByteOffset offset, out ByteOffset startIndex, out UInt32 paragraphCount);
// ======================================================
// edition commands ... need more investigation
// ======================================================
    //should always work on the global scrap
    OSStatus Cut() ;

    OSStatus Copy() ;

    OSStatus Paste() ;

    boolean CanPaste() ;

    OSStatus Clear() ;

    OSStatus IsUndoActive(out boolean isActive, out EditCommandID theCommand);

    OSStatus UndoLastEditCommand();

    OSStatus DragEnteredViewedText(in DragReference theDrag,out boolean acceptIt) ;

    OSStatus DragInViewedText(in DragReference theDrag) ;

    OSStatus DragLeaveViewedText(in DragReference theDrag) ;

    OSStatus Drop(in DragReference theDrag) ;

    OSStatus GetHilileRegionHandle(out RgnHandle theRgn);

    OSStatus SetTextChangedFlag();
    OSStatus ResetTextChangedFlag();
    boolean  IsTextChanged();

// ======================================================
// events,keyborad, command interface ...
//*** need interface for let the caller know that he needs to create a dragreference and
//track it.
// ======================================================
    OSStatus MouseIsDown(in Point qdMouseCoordinate/*port relative*/,
                            in EventModifiers modifiers,
                            in AppleEvent theEvent, inout AppleEvent reply,in AEHandlerTableRef handlerTableRef);

    OSStatus MouseHasMoved(in Point qdMouseCoordinate/*port relative*/,
                        in EventModifiers modifiers,
                        in AppleEvent theEvent, inout AppleEvent reply,in AEHandlerTableRef handlerTableRef);

    OSStatus MouseStopped(in Point qdMouseCoordinate/*port relative*/,
                        in EventModifiers modifiers,
                        in AppleEvent theEvent, inout AppleEvent reply,in AEHandlerTableRef handlerTableRef);

    OSStatus MouseIsUp(in Point qdMouseCoordinate/*port relative*/,
                        in EventModifiers modifiers,
                        in AppleEvent theEvent, inout AppleEvent reply,in AEHandlerTableRef handlerTableRef);


    //Handle the modern text event class.
    OSStatus  HandleTextAEvent(in AEEventID eventID ,in AppleEvent appleEvent, inout AppleEvent reply,in AEHandlerTableRef handlerTableRef) ;

    OSStatus TextGainKeyboardFocus() ;

    OSStatus TextGiveUpKeyboardFocus() ;//should be called at window deactivation or should we add a WindowActivate method ??

    boolean HasKeyboardFocus();

    OSStatus TextInputObjectChanged(in LocaleIdentifier theLocaleID);


    OSStatus GetAETable(out AEHandlerTableRef theTable);// should return the list of AE the engine handles


//click loop proc
    OSStatus SetTextMouseDownTrackActionRoutine(in MouseDownInTextTrackProcPtr theMouseTrackProcPtr, in void* userData) ;


    implementation {

        passthru C_h =     "#include <Types.h>"
                        "#include <Collections.h>"
                        "#include <Drag.h>"
                        "#include <Events.h>"
                        "#include <Quickdraw.h>"
                        "#include <TextObjects.h>"
                        "#include <MixedMode.h>"
                        "#include <TextCommon.h>"
                        "#include <TextEngineTypes.h>"
                        "#include <TextEdit.h>" ;

        passthru C_xh = "#include <Types.h>"
                        "#include <Collections.h>"
                        "#include <Drag.h>"
                        "#include <Events.h>"
                        "#include <Quickdraw.h>"
                        "#include <TextObjects.h>"
                        "#include <MixedMode.h>"
                        "#include <TextCommon.h>"
                        "#include <TextEngineTypes.h>"
                        "#include <TextEdit.h>" ;

        releaseorder:      InitTextInstance,
                        SetTextFrameDimensions,
                        GetTextFrameDimensions,
                        SetTextViewFrame,
                        GetTextViewFrame,
                        SetTextMargins,
                        GetTextMargins,
                        RefreshText,
                        EnableDrawingText,
                        DisableDrawingText,
                        IsDrawingTextEnabled,
                        AboutToImage,
                        EndImaging,
                        SetWholeTextTo,
                        GetWholeTextSize,
                        WriteWholeTextToPtr,
                        GetWholeScrapStyleCount,
                        WriteWholeScrapStyleToPtr,
                        GetStorageSizeForTextDataStructure,
                        SaveDataStructureToPtr,
                        ReadDataStructureFromPtr,
                        SetText,
                        InsertText,
                        DeleteText,
                        GetText,
                        SelectTextRange,
                        GetSelectedTextRange,
                        RevealTextRange,
                        ScrollTextViewTo,
                        GetScroll,
                        GetTextHeight,
                        SetTextAttribute,
                        GetTextAttribute,
                        NewTextAttributeIterator,
                        TextAttributeIterateForward,
                        DisposeTextAttributeIterator,
                        SetTextCollectionAttribute,
                        GetSharedTextAttribute,
                        GetNextTextElement,
                        GetPriorTextElement,
                        GetEnclosingTextElement,
                        ByteOffsetToPixel,
                        PixelToByteOffset,
                        ByteOffsetToWord,
                        NthWordInRange,
                        LineToByteOffsets,
                        ByteOffsetToLine,
                        ByteOffsetToParagraph,
                        GetCountChars,
                        GetCountWords,
                        GetCountLines,
                        GetCountParagraphs,
                        Cut,
                        Copy,
                        CanPaste,
                        Paste,
                        Clear,
                        IsUndoActive,
                        UndoLastEditCommand,
                        DragEnteredViewedText,
                        DragInViewedText,
                        DragLeaveViewedText,
                        Drop,
                        SetTextChangedFlag,
                        ResetTextChangedFlag,
                        IsTextChanged,
                        GetHilileRegionHandle,
                        MouseIsDown,
                        MouseStopped,
                        MouseIsUp,
                        MouseHasMoved,
                        HandleTextAEvent,
                        TextGainKeyboardFocus,
                        TextGiveUpKeyboardFocus,
                        HasKeyboardFocus,
                        TextInputObjectChanged,
                        GetAETable,
                        SetTextMouseDownTrackActionRoutine,
                        EnableUICommand,
                        DisableUICommand,
                        IsUICommandEnabled,
                        DoIDleAction,
                        reserved0,
                        reserved1;
    };
};


#endif //#ifndef __TEXTENGINESYSTEM_IDL__